package com.hbnu.common.dao;

import com.hbnu.common.entity.CheckInItem;

import java.sql.SQLException;
import java.util.List;

/**
 * 打卡项数据访问对象（DAO）接口。
 * 定义了与打卡项相关的所有数据操作契约，包括新增、查询、打卡、更新和删除等。
 */

public interface CheckInItemDao {

    /**
     * 向数据库中新增一个打卡项。
     *
     * @param itemName 打卡项的名称（如"晨跑"、"背单词"）。
     * @param username 该打卡项所属的用户名。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或插入操作未影响任何行，将抛出此异常。
     */
    void addItem(String itemName, String username) throws SQLException;

    /**
     * 根据打卡项ID查询其详细信息。
     * 查询结果包含打卡项的基本信息以及今日是否已打卡的状态。
     *
     * @param itemId 要查询的打卡项ID。
     * @return 一个包含打卡项详细信息的{@link CheckInItem}实体对象，如果未找到则返回null。
     * @throws SQLException 如果数据库连接失败或SQL执行失败，将抛出此异常。
     */
    CheckInItem getItemById(int itemId) throws SQLException;

    /**
     * 查询指定用户创建的所有打卡项。
     * 查询结果包含每个打卡项的基本信息以及今日是否已打卡的状态。
     *
     * @param username 要查询其打卡项的用户名。
     * @return 一个包含所有打卡项的{@link List}，如果用户没有创建任何打卡项，则返回一个空列表。
     * @throws SQLException 如果数据库连接失败或SQL执行失败，将抛出此异常。
     */
    List<CheckInItem> getItemsOfUser(String username) throws SQLException;

    /**
     * 处理指定打卡项的今日打卡逻辑。
     * 此操作是一个原子事务，包含以下步骤：
     * 1. 向打卡记录表中插入一条今日的打卡记录。
     * 2. 更新打卡项的总打卡天数（total_days）。
     * 3. 计算并更新打卡项的连续打卡天数（continuous_days）。
     *
     * @param itemId 要进行打卡操作的打卡项ID。
     * @throws SQLException 如果数据库操作失败、事务提交/回滚失败，或打卡项不存在，将抛出此异常。
     */
    void checkInToday(int itemId) throws SQLException;

    /**
     * 更新指定打卡项的名称。
     *
     * @param itemId  要更新名称的打卡项ID。
     * @param newName 打卡项的新名称。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或未找到要更新的打卡项，将抛出此异常。
     */
    void updateItem(int itemId, String newName) throws SQLException;

    /**
     * 根据ID删除指定的打卡项。
     *
     * @param itemId 要删除的打卡项ID。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或未找到要删除的打卡项，将抛出此异常。
     */
    void deleteItem(int itemId) throws SQLException;
}